home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib / tk / GetBitmap.man < prev    next >
Encoding:
Text File  |  1992-08-24  |  11.8 KB  |  405 lines
  1. '\"
  2. '\" Copyright 1990 Regents of the University of California
  3. '\" Permission to use, copy, modify, and distribute this
  4. '\" documentation for any purpose and without fee is hereby
  5. '\" granted, provided that this notice appears in all copies.
  6. '\" The University of California makes no representations about
  7. '\" the suitability of this material for any purpose.  It is
  8. '\" provided "as is" without express or implied warranty.
  9. '\" 
  10. '\" $Header: /user6/ouster/wish/man/RCS/GetBitmap.man,v 1.7 92/05/21 11:32:21 ouster Exp $ SPRITE (Berkeley)
  11. '\" 
  12. .\" The definitions below are for supplemental macros used in Sprite
  13. .\" manual entries.
  14. .\"
  15. .\" .HS name section [date [version]]
  16. .\"    Replacement for .TH in other man pages.  See below for valid
  17. .\"    section names.
  18. .\"
  19. .\" .AP type name in/out [indent]
  20. .\"    Start paragraph describing an argument to a library procedure.
  21. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  22. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  23. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  24. .\"    needed;  use .AS below instead)
  25. .\"
  26. .\" .AS [type [name]]
  27. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  28. .\"    name are examples of largest possible arguments that will be passed
  29. .\"    to .AP later.  If args are omitted, default tab stops are used.
  30. .\"
  31. .\" .BS
  32. .\"    Start box enclosure.  From here until next .BE, everything will be
  33. .\"    enclosed in one large box.
  34. .\"
  35. .\" .BE
  36. .\"    End of box enclosure.
  37. .\"
  38. .\" .VS
  39. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  40. .\"    of man pages.
  41. .\"
  42. .\" .VE
  43. .\"    End of vertical sidebar.
  44. .\"
  45. .\" .DS
  46. .\"    Begin an indented unfilled display.
  47. .\"
  48. .\" .DE
  49. .\"    End of indented unfilled display.
  50. .\"
  51. '\"    # Heading for Sprite man pages
  52. .de HS
  53. .if '\\$2'cmds'       .TH \\$1 1 \\$3 \\$4
  54. .if '\\$2'lib'        .TH \\$1 3 \\$3 \\$4
  55. .if '\\$2'tcl'        .TH \\$1 3 \\$3 \\$4
  56. .if '\\$2'tk'         .TH \\$1 3 \\$3 \\$4
  57. .if t .wh -1.3i ^B
  58. .nr ^l \\n(.l
  59. .ad b
  60. ..
  61. '\"    # Start an argument description
  62. .de AP
  63. .ie !"\\$4"" .TP \\$4
  64. .el \{\
  65. .   ie !"\\$2"" .TP \\n()Cu
  66. .   el          .TP 15
  67. .\}
  68. .ie !"\\$3"" \{\
  69. .ta \\n()Au \\n()Bu
  70. \&\\$1    \\fI\\$2\\fP    (\\$3)
  71. .\".b
  72. .\}
  73. .el \{\
  74. .br
  75. .ie !"\\$2"" \{\
  76. \&\\$1    \\fI\\$2\\fP
  77. .\}
  78. .el \{\
  79. \&\\fI\\$1\\fP
  80. .\}
  81. .\}
  82. ..
  83. '\"    # define tabbing values for .AP
  84. .de AS
  85. .nr )A 10n
  86. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  87. .nr )B \\n()Au+15n
  88. .\"
  89. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  90. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  91. ..
  92. '\"    # BS - start boxed text
  93. '\"    # ^y = starting y location
  94. '\"    # ^b = 1
  95. .de BS
  96. .br
  97. .mk ^y
  98. .nr ^b 1u
  99. .if n .nf
  100. .if n .ti 0
  101. .if n \l'\\n(.lu\(ul'
  102. .if n .fi
  103. ..
  104. '\"    # BE - end boxed text (draw box now)
  105. .de BE
  106. .nf
  107. .ti 0
  108. .mk ^t
  109. .ie n \l'\\n(^lu\(ul'
  110. .el \{\
  111. .\"    Draw four-sided box normally, but don't draw top of
  112. .\"    box if the box started on an earlier page.
  113. .ie !\\n(^b-1 \{\
  114. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  115. .\}
  116. .el \}\
  117. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  118. .\}
  119. .\}
  120. .fi
  121. .br
  122. .nr ^b 0
  123. ..
  124. '\"    # VS - start vertical sidebar
  125. '\"    # ^Y = starting y location
  126. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  127. .de VS
  128. .mk ^Y
  129. .ie n 'mc \s12\(br\s0
  130. .el .nr ^v 1u
  131. ..
  132. '\"    # VE - end of vertical sidebar
  133. .de VE
  134. .ie n 'mc
  135. .el \{\
  136. .ev 2
  137. .nf
  138. .ti 0
  139. .mk ^t
  140. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  141. .sp -1
  142. .fi
  143. .ev
  144. .\}
  145. .nr ^v 0
  146. ..
  147. '\"    # Special macro to handle page bottom:  finish off current
  148. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  149. '\"    # page bottom macro.
  150. .de ^B
  151. .ev 2
  152. 'ti 0
  153. 'nf
  154. .mk ^t
  155. .if \\n(^b \{\
  156. .\"    Draw three-sided box if this is the box's first page,
  157. .\"    draw two sides but no top otherwise.
  158. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  159. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  160. .\}
  161. .if \\n(^v \{\
  162. .nr ^x \\n(^tu+1v-\\n(^Yu
  163. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  164. .\}
  165. .bp
  166. 'fi
  167. .ev
  168. .if \\n(^b \{\
  169. .mk ^y
  170. .nr ^b 2
  171. .\}
  172. .if \\n(^v \{\
  173. .mk ^Y
  174. .\}
  175. ..
  176. '\"    # DS - begin display
  177. .de DS
  178. .RS
  179. .nf
  180. .sp
  181. ..
  182. '\"    # DE - end display
  183. .de DE
  184. .fi
  185. .RE
  186. .sp .5
  187. ..
  188. .HS Tk_GetBitmap tk
  189. .BS
  190. .SH NAME
  191. Tk_GetBitmap, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmap, Tk_GetBitmapFromData \- maintain database of single-plane pixmaps
  192. .SH SYNOPSIS
  193. .nf
  194. \fB#include <tk.h>\fR
  195. .sp
  196. Pixmap
  197. \fBTk_GetBitmap(\fIinterp, tkwin, id\fB)\fR
  198. .sp
  199. .VS
  200. int
  201. \fBTk_DefineBitmap(\fIinterp, nameId, source, width, height\fR)\fR
  202. .VE
  203. .sp
  204. Tk_Uid
  205. \fBTk_NameOfBitmap(\fIbitmap\fB)\fR
  206. .sp
  207. .VS
  208. \fBTk_SizeOfBitmap(\fIbitmap, widthPtr, heightPtr\fB)\fR
  209. .VE
  210. .sp
  211. \fBTk_FreeBitmap(\fIbitmap\fB)\fR
  212. .sp
  213. Pixmap
  214. \fBTk_GetBitmapFromData(\fIinterp, tkwin, source, width, height\fB)\fR
  215. .SH ARGUMENTS
  216. .AS "unsigned long" *pixelPtr
  217. .AP Tcl_Interp *interp in
  218. Interpreter to use for error reporting.
  219. .AP Tk_Window tkwin in
  220. Token for window in which the bitmap will be used.
  221. .AP Tk_Uid id in
  222. Description of bitmap;  see below for possible values.
  223. .AP Tk_Uid *nameId in
  224. Name for new bitmap to be defined.
  225. .AP char *source in
  226. Data for bitmap, in standard bitmap format.
  227. Must be stored in static memory whose value will never change.
  228. .AP "unsigned int" width in
  229. Width of bitmap.
  230. .AP "unsigned int" height in
  231. Height of bitmap.
  232. .AP "unsigned int" *widthPtr out
  233. Pointer to word to fill in with \fIbitmap\fR's width.
  234. .VS
  235. .AP "unsigned int" *heightPtr out
  236. Pointer to word to fill in with \fIbitmap\fR's height.
  237. .AP Pixmap bitmap in
  238. Identifier for a bitmap allocated by \fBTk_GetBitmap\fR.
  239. .VE
  240. .BE
  241.  
  242. .SH DESCRIPTION
  243. .PP
  244. These procedures manage a collection of bitmaps (one-plane pixmaps)
  245. being used by an application.  The procedures allow bitmaps to be
  246. re-used efficiently, thereby avoiding server overhead, and also
  247. allow bitmaps to be named with character strings.
  248. .PP
  249. \fBTk_GetBitmap\fR takes as argument a Tk_Uid describing a bitmap.
  250. It returns a Pixmap identifier for a bitmap corresponding to the
  251. description.  It re-uses an existing bitmap, if possible, and
  252. creates a new one otherwise.  At present, \fIid\fR must have
  253. .VS
  254. one of the following forms:
  255. .TP 20
  256. \fB@\fIfileName\fR
  257. \fIFileName\fR must be the name of a file containing a bitmap
  258. description in the standard X11 or X10 format.
  259. .TP 20
  260. \fIname\fR
  261. \fIName\fR must be the name of a bitmap defined previously with
  262. a call to \fBTk_DefineBitmap\fR.  The following names are pre-defined
  263. by Tk:
  264. .RS
  265. .TP
  266. \fBgray50\fR
  267. 50% gray: a checkerboard pattern where every other bit is on.
  268. .TP
  269. \fBgray25\fR
  270. 25% gray: a pattern where 25% of the bits are on, consisting of all the
  271. bit positions that can be reached by a chess knight starting at (0,0).
  272. .RE
  273. .VE
  274. .LP
  275. Under normal conditions, \fBTk_GetBitmap\fR
  276. returns an identifier for the requested bitmap.  If an error
  277. occurs in creating the bitmap, such as when \fIid\fR refers
  278. to a non-existent file, then \fBNone\fR is returned and an error
  279. message is left in \fIinterp->result\fR.
  280. .PP
  281. \fBTk_DefineBitmap\fR associates a name with
  282. .VS
  283. in-memory bitmap data so that the name can be used in later
  284. calls to \fBTk_GetBitmap\fR.  The \fInameId\fR
  285. argument gives a name for the bitmap;  it must not previously
  286. have been used in a call to \fBTk_DefineBitmap\fR.
  287. The arguments \fIsource\fR, \fIwidth\fR, and \fIheight\fR
  288. describe the bitmap.
  289. \fBTk_DefineBitmap\fR normally returns TCL_OK;  if an error occurs
  290. (e.g. a bitmap named \fInameId\fR has already been defined) then
  291. TCL_ERROR is returned and an error message is left in
  292. \fIinterp->result\fR.
  293. Note:  \fBTk_DefineBitmap\fR expects the memory pointed to by
  294. \fIsource\fR to be static:  \fBTk_DefineBitmap\fR doesn't make
  295. a private copy of this memory, but uses the bytes pointed to
  296. by \fIsource\fR later in calls to \fBTk_GetBitmap\fR.
  297. .VE
  298. .PP
  299. Typically \fBTk_DefineBitmap\fR is used by \fB#include\fR-ing a
  300. bitmap file directly into a C program and then referencing
  301. the variables defined by the file.
  302. For example, suppose there exists a file \fBstip.bitmap\fR,
  303. which was created by the \fBbitmap\fR program and contains
  304. a stipple pattern.
  305. The following code uses \fBTk_DefineBitmap\fR to define a
  306. new bitmap named \fBfoo\fR:
  307. .nf
  308. .RS
  309. \fCPixmap bitmap;
  310. #include "stip.bitmap"
  311. Tk_DefineBitmap(interp, Tk_GetUid("foo"), stip_bits,
  312.     stip_width, stip_height);
  313. \&...
  314. bitmap = Tk_GetBitmap(interp, tkwin, Tk_GetUid("foo"));\fR
  315. .RE
  316. .fi
  317. This code causes the bitmap file to be read
  318. at compile-time and incorporates the bitmap information into
  319. the program's executable image.  The same bitmap file could be
  320. read at run-time using \fBTk_GetBitmap\fR:
  321. .nf
  322. .RS
  323. \fCPixmap bitmap;
  324. bitmap = Tk_GetBitmap(interp, tkwin, Tk_GetUid("@stip.bitmap"));\fR
  325. .RE
  326. .fi
  327. The second form is a bit more flexible (the file could be modified
  328. after the program has been compiled, or a different string could be
  329. provided to read a different file), but it is a little slower and
  330. requires the bitmap file to exist separately from the program.
  331. .PP
  332. \fBTk_GetBitmap\fR maintains a
  333. database of all the bitmaps that have been created.
  334. Whenever possible, it will return an existing bitmap rather
  335. than creating a new one.
  336. This approach can substantially reduce server overhead, so
  337. \fBTk_GetBitmap\fR should generally be used in preference to Xlib
  338. procedures like \fBXReadBitmapFile\fR or \fBXGetBitmapFromData\fR,
  339. which create a new bitmap on each call.
  340. .PP
  341. The bitmaps returned by \fBTk_GetBitmap\fR
  342. are shared, so callers should never modify them.
  343. If a bitmap must be modified dynamically, then it should be
  344. created by calling Xlib procedures such as \fBXReadBitmapFile\fR
  345. or \fBXCreatePixmap\fR directly.
  346. .PP
  347. The procedure \fBTk_NameOfBitmap\fR is roughly the inverse of
  348. \fBTk_GetBitmap\fR.
  349. Given an X Pixmap argument, it returns the \fIid\fR that was
  350. passed to \fBTk_GetBitmap\fR when the bitmap was created.
  351. .VS
  352. \fIBitmap\fR must have been the return value from a previous
  353. call to \fBTk_GetBitmap\fR.
  354. .VE
  355. .PP
  356. \fBTk_SizeOfBitmap\fR returns the dimensions of its \fIbitmap\fR
  357. .VS
  358. argument in the words pointed to by the \fIwidthPtr\fR and
  359. \fIheightPtr\fR arguments.  As with \fBTk_NameOfBitmap\fR,
  360. \fIbitmap\fR must have been created by \fBTk_GetBitmap\fR.
  361. .VE
  362. .PP
  363. When a bitmap returned by \fBTk_GetBitmap\fR
  364. is no longer needed, \fBTk_FreeBitmap\fR should be called to release it.
  365. There should be exactly one call to \fBTk_FreeBitmap\fR for
  366. each call to \fBTk_GetBitmap\fR.
  367. When a bitmap is no longer in use anywhere (i.e. it has been freed as
  368. many times as it has been gotten) \fBTk_FreeBitmap\fR will release
  369. it to the X server and delete it from the database.
  370. .PP
  371. The procedure \fBTk_GetBitmapFromData\fR is a historical relic
  372. .VS
  373. from a time before \fBTk_DefineBitmap\fR existed;  its use is
  374. discouraged nowadays and it may be deleted soon.
  375. \fBTk_GetBitmapFromData\fR serves as a combination of
  376. \fBTk_DefineBitmap\fR and \fBTk_GetBitmap\fR:  given an in-memory
  377. description for a bitmap similar to what would be passed to
  378. \fBTk_DefineBitmap\fR (\fIsource, width, \fRand\fI height\fR),
  379. it returns a bitmap corresponding to that description that is
  380. suitable for use in window \fItkwin\fR.
  381. At present it does this by calling \fBTk_DefineBitmap\fR to
  382. define a name of the form ``\fB_tk\fInum\fR'' where \fInum\fR
  383. is an integer that starts at 1 and increments for each new
  384. combination of \fIsource\fR, \fIwidth\fR, and \fIheight\fR.
  385. Then it calls \fBTk_GetBitmap\fR.
  386. \fBTk_GetBitmapFromData\fR keeps a database of names and
  387. data, so that if the same \fIsource\fR, \fIwidth\fR, and \fIheight\fR
  388. are used again later, \fBTk_GetBitmapFromData\fR will re-use
  389. the original name.
  390. .VE
  391.  
  392. .SH BUGS
  393. In determining whether an existing bitmap can be used to satisfy
  394. a new request, \fBTk_GetBitmap\fR
  395. considers only the immediate value of its \fIid\fR argument.  For
  396. example, when a file name is passed to \fBTk_GetBitmap\fR,
  397. \fBTk_GetBitmap\fR will assume it is safe to re-use an existing
  398. bitmap created from the same file name:  it will not check to
  399. see whether the file itself has changed, or whether the current
  400. directory has changed, thereby causing the name to refer to
  401. a different file.
  402.  
  403. .SH KEYWORDS
  404. bitmap, pixmap
  405.